/*
 *
 *      Copyright (c) 2018-2025, lengleng All rights reserved.
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions are met:
 *
 * Redistributions of source code must retain the above copyright notice,
 *  this list of conditions and the following disclaimer.
 *  Redistributions in binary form must reproduce the above copyright
 *  notice, this list of conditions and the following disclaimer in the
 *  documentation and/or other materials provided with the distribution.
 *  Neither the name of the pig4cloud.com developer nor the names of its
 *  contributors may be used to endorse or promote products derived from
 *  this software without specific prior written permission.
 *  Author: lengleng (wangiegie@gmail.com)
 *
 */

package com.pig4cloud.pig.admin.service;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.baomidou.mybatisplus.extension.service.IService;
import com.pig4cloud.pig.admin.api.dto.RegisterUserDTO;
import com.pig4cloud.pig.admin.api.dto.UserDTO;
import com.pig4cloud.pig.admin.api.dto.UserInfo;
import com.pig4cloud.pig.admin.api.entity.SysUser;
import com.pig4cloud.pig.admin.api.vo.UserExcelVO;
import com.pig4cloud.pig.admin.api.vo.UserVO;
import com.pig4cloud.pig.common.core.util.R;
import org.springframework.validation.BindingResult;

import java.util.List;

/**
 * 系统用户服务接口
 * <p>
 * 提供用户管理的核心业务逻辑处理，包括用户的增删改查、权限分配、密码管理等功能。
 * 支持用户信息导入导出、批量操作、社交账号绑定等扩展功能，是系统用户管理的核心服务
 * </p>
 *
 * @author lengleng
 * @date 2025/05/30
 */
public interface SysUserService extends IService<SysUser> {

	/**
	 * 根据用户信息查询用户详情
	 * <p>
	 * 支持通过用户名、手机号、社交账号等多种方式查询用户信息，
	 * 返回包含用户基本信息、角色、权限、部门等完整信息
	 * </p>
	 * 
	 * @param query 用户查询条件，可包含用户名、手机号等
	 * @return 包含用户详细信息的响应结果
	 */
	R<UserInfo> getUserInfo(UserDTO query);

	/**
	 * 分页查询用户信息（包含角色信息）
	 * <p>
	 * 支持按用户名、手机号、部门等条件查询，返回结果包含用户的角色信息。
	 * 用于用户管理界面的列表展示，支持多条件组合查询
	 * </p>
	 * 
	 * @param page 分页对象，包含页码、每页大小等信息
	 * @param userDTO 查询参数，包含用户名、部门ID等过滤条件
	 * @return 用户信息分页结果，包含角色信息
	 */
	IPage getUsersWithRolePage(Page page, UserDTO userDTO);

	/**
	 * 批量删除用户
	 * <p>
	 * 支持批量删除多个用户，删除时会同步清理用户相关的角色关联、
	 * 岗位关联等信息，确保数据完整性
	 * </p>
	 * 
	 * @param ids 用户ID数组
	 * @return 删除是否成功
	 */
	Boolean removeUserByIds(Long[] ids);

	/**
	 * 更新当前登录用户基本信息
	 * <p>
	 * 允许用户修改自己的基本信息，如昵称、邮箱、头像等。
	 * 不包含敏感信息如角色、部门的修改
	 * </p>
	 * 
	 * @param userDto 用户信息DTO，包含要更新的字段
	 * @return 包含操作结果的响应对象
	 */
	R<Boolean> updateUserInfo(UserDTO userDto);

	/**
	 * 更新指定用户信息
	 * <p>
	 * 管理员功能，可以更新任意用户的完整信息，包括角色、部门、岗位等。
	 * 支持同时更新用户基本信息和权限关联信息
	 * </p>
	 * 
	 * @param userDto 用户信息DTO对象，包含用户ID和要更新的字段
	 * @return 更新是否成功
	 */
	Boolean updateUser(UserDTO userDto);

	/**
	 * 通过ID查询用户信息
	 * <p>
	 * 查询指定用户的详细信息，包含角色、部门、岗位等关联信息。
	 * 用于用户编辑页面的数据回显
	 * </p>
	 * 
	 * @param id 用户ID
	 * @return 用户视图对象，包含完整的用户信息
	 */
	UserVO getUserById(Long id);

	/**
	 * 保存用户信息
	 * <p>
	 * 创建新用户，同时处理用户的角色分配、部门设置、岗位分配等。
	 * 默认密码会进行加密处理，支持发送欢迎邮件或短信
	 * </p>
	 * 
	 * @param userDto 用户信息DTO对象，包含完整的用户创建信息
	 * @return 保存是否成功
	 */
	Boolean saveUser(UserDTO userDto);

	/**
	 * 查询全部的用户
	 * <p>
	 * 不分页查询所有符合条件的用户，主要用于Excel导出功能。
	 * 返回数据已转换为Excel导出格式
	 * </p>
	 * 
	 * @param userDTO 查询条件，为空时查询所有用户
	 * @return 用户Excel视图对象列表
	 */
	List<UserExcelVO> listUsers(UserDTO userDTO);

	/**
	 * Excel批量导入用户
	 * <p>
	 * 支持通过Excel批量创建用户，自动处理数据验证、重复检查、
	 * 默认密码生成等。导入失败时会返回详细的错误信息
	 * </p>
	 * 
	 * @param excelVOList Excel解析后的用户数据列表
	 * @param bindingResult 数据验证结果，包含格式错误等信息
	 * @return 导入结果，包含成功数量和失败详情
	 */
	R importUsers(List<UserExcelVO> excelVOList, BindingResult bindingResult);

	/**
	 * 用户自助注册
	 * <p>
	 * 提供用户自助注册功能，支持手机号验证、邮箱验证等方式。
	 * 注册成功后分配默认角色和权限
	 * </p>
	 * 
	 * @param userDto 注册用户信息，包含用户名、密码、验证码等
	 * @return 注册结果，成功返回true
	 */
	R<Boolean> registerUser(RegisterUserDTO userDto);

	/**
	 * 锁定/解锁用户账号
	 * <p>
	 * 切换用户的锁定状态，锁定的用户无法登录系统。
	 * 通常用于处理异常账号或违规用户
	 * </p>
	 * 
	 * @param username 要锁定的用户名
	 * @return 包含操作结果的响应对象，true表示操作成功
	 */
	R<Boolean> lockUser(String username);

	/**
	 * 修改用户密码
	 * <p>
	 * 支持管理员重置密码和用户自助修改密码两种场景。
	 * 修改密码时会进行旧密码验证和密码强度检查
	 * </p>
	 * 
	 * @param userDto 包含用户ID、旧密码、新密码等信息的DTO对象
	 * @return 操作结果，包含成功状态和错误信息
	 */
	R changePassword(UserDTO userDto);

	/**
	 * 校验当前用户密码
	 * <p>
	 * 验证当前登录用户的密码是否正确，用于敏感操作前的二次验证。
	 * 如修改密码、删除重要数据等场景
	 * </p>
	 * 
	 * @param password 待校验的密码明文
	 * @return 校验结果，正确返回成功，错误返回失败原因
	 */
	R checkPassword(String password);

}
